---
title: "DateInput"
description: "DateInput is a component that allows users to enter and edit date and time values using a keyboard. Each part of a date value is displayed in an individually editable segment."
---

import {dateInputContent} from "@/content/components/date-input";

# DateInput

DateInput is a component that allows users to enter and edit date and time values using a keyboard.
Each part of a date value is displayed in an individually editable segment.

<ComponentLinks component="date-input" storybook="dateinput" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add date-input",
    npm: "npm install @heroui/date-input",
    yarn: "yarn add @heroui/date-input",
    pnpm: "pnpm add @heroui/date-input",
    bun: "bun add @heroui/date-input",
  }}
/>

## Import

<ImportTabs
  commands={{
    main: 'import {DateInput} from "@heroui/react";',
    individual: 'import {DateInput} from "@heroui/date-input";',
  }}
/>

## Usage

<CodeDemo title="Usage" files={dateInputContent.usage} />

### Disabled

<CodeDemo title="Disabled" files={dateInputContent.disabled} />

### Read Only

<CodeDemo title="Read Only" files={dateInputContent.readOnly} />

### Required

<CodeDemo title="Required" files={dateInputContent.required} />

### Variants

<CodeDemo title="Variants" files={dateInputContent.variants} />

### Label Placements

You can change the position of the label by setting the `labelPlacement` property to `inside`, `outside` or `outside-left`.

<CodeDemo title="Label Placements" files={dateInputContent.labelPlacements} />

> **Note**: If the `label` is not passed, the `labelPlacement` property will be `outside` by default.

### Start & End Content

You can use the `startContent` and `endContent` properties to add content to the start and end of the `DateInput`.

<CodeDemo title="Start and End Content" files={dateInputContent.startEndContent} />

### With Description

You can add a description to the input by passing the `description` property.

<CodeDemo title="With Description" files={dateInputContent.description} />

### With Error Message

You can combine the `isInvalid` and `errorMessage` properties to show an invalid input.

<CodeDemo title="With Error Message" files={dateInputContent.errorMessage} />

You can also pass an error message as a function. This allows for dynamic error message handling based on the [ValidationResult](https://github.com/adobe/react-spectrum/blob/1cacbf1d438675feb3859fee54b17e620b458d9c/packages/%40react-types/shared/src/inputs.d.ts#L44-L51).

<CodeDemo title="With Error Message Function" files={dateInputContent.errorMessageFunction} />

### Controlled

You can use the `value` and `onChange` properties to control the input value.

<CodeDemo title="Controlled" files={dateInputContent.controlled} />

### Time Zones

DateInput is time zone aware when a `ZonedDateTime` object is provided as the value. In this case, the time zone abbreviation is displayed,
and time zone concerns such as daylight saving time are taken into account when the value is manipulated.

[@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/) includes functions for parsing strings
in multiple formats into `ZonedDateTime` objects.

<PackageManagers
  commands={{
    npm: "npm install @internationalized/date@3.10.0",
    yarn: "yarn add @internationalized/date@3.10.0",
    pnpm: "pnpm add @internationalized/date@3.10.0",
  }}
/>

```jsx
import {parseZonedDateTime} from "@internationalized/date";
```

<Spacer y={2} />

<CodeDemo title="Time Zones" files={dateInputContent.timeZones} />

### Granularity

The granularity prop allows you to control the smallest unit that is displayed by DateInput By default,
the value is displayed with "day" granularity (year, month, and day),
and `CalendarDateTime` and `ZonedDateTime` values are displayed with "minute" granularity.

[@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/) includes functions for parsing strings
in multiple formats into `ZonedDateTime` objects.

<PackageManagers
  commands={{
    npm: "npm install @internationalized/date@3.10.0 @react-aria/i18n@3.12.13",
    yarn: "yarn add @internationalized/date@3.10.0 @react-aria/i18n@3.12.13",
    pnpm: "pnpm add @internationalized/date@3.10.0 @react-aria/i18n@3.12.13",
  }}
/>

```jsx
import {DateValue, now, parseAbsoluteToLocal} from "@internationalized/date";
import {useDateFormatter} from "@react-aria/i18n";
```

<Spacer y={2} />

<CodeDemo title="Time Zones" files={dateInputContent.granularity} />

### Min Date And Max Date

The minValue and maxValue props can also be used to ensure the value is within a specific range.

[@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/) includes functions for parsing strings
in multiple formats into `ZonedDateTime` objects.

<PackageManagers
  commands={{
    npm: "npm install @internationalized/date@3.10.0",
    yarn: "yarn add @internationalized/date@3.10.0",
    pnpm: "pnpm add @internationalized/date@3.10.0",
  }}
/>

```jsx
import {getLocalTimeZone, parseDate, today} from "@internationalized/date";
```

<CodeDemo title="Min Date And Max Date" files={dateInputContent.minAndMaxDate} />

### International Calendar

DateInput supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more.
Dates are automatically displayed in the appropriate calendar system for the user's locale.
The calendar system can be overridden using the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string),
passed to the [I18nProvider](https://react-spectrum.adobe.com/react-aria/I18nProvider.html) component.

[@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/) includes functions for parsing strings
in multiple formats into `ZonedDateTime` objects.

<PackageManagers
  commands={{
    npm: "npm install @internationalized/date@3.10.0 @react-aria/i18n@3.12.13",
    yarn: "yarn add @internationalized/date@3.10.0 @react-aria/i18n@3.12.13",
    pnpm: "pnpm add @internationalized/date@3.10.0 @react-aria/i18n@3.12.13",
  }}
/>

```jsx
import {DateValue, now, parseAbsoluteToLocal} from "@internationalized/date";
import {I18nProvider} from "@react-aria/i18n";
```

<CodeDemo title="International Calendar" files={dateInputContent.internationalCalendar} />

### Hide Time Zone

When a `ZonedDateTime` object is provided as the value to DateInput, the time zone abbreviation is displayed by default.
However, if this is displayed elsewhere or implicit based on the usecase, it can be hidden using the hideTimeZone option.

[@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/) includes functions for parsing strings
in multiple formats into `ZonedDateTime` objects.

<PackageManagers
  commands={{
    npm: "npm install @internationalized/date@3.10.0",
    yarn: "yarn add @internationalized/date@3.10.0",
    pnpm: "pnpm add @internationalized/date@3.10.0",
  }}
/>

```jsx
import {parseZonedDateTime} from "@internationalized/date";
```

<CodeDemo title="Hide Time Zone" files={dateInputContent.hideTimeZone} />

### Hourly Cycle

By default, DateInput displays times in either 12 or 24 hour hour format depending on the user's locale.
However, this can be overridden using the `hourCycle` prop if needed for a specific usecase.
This example forces DateInput to use 24-hour time, regardless of the locale.

[@internationalized/date](https://react-spectrum.adobe.com/internationalized/date/) includes functions for parsing strings
in multiple formats into `ZonedDateTime` objects.

<PackageManagers
  commands={{
    npm: "npm install @internationalized/date@3.10.0",
    yarn: "yarn add @internationalized/date@3.10.0",
    pnpm: "pnpm add @internationalized/date@3.10.0",
  }}
/>

```jsx
import {parseZonedDateTime} from "@internationalized/date";
```

<CodeDemo title="Hide Time Zone" files={dateInputContent.hourlyCycle} />

## Slots

- **base**: Input wrapper, it handles alignment, placement, and general appearance.
- **label**: Label of the date-input, it is the one that is displayed above, inside or left of the date-input.
- **inputWrapper**: Wraps the `label` (when it is inside) and the `innerWrapper`.
- **input**: The date-input element.
- **innerWrapper**: Wraps the `input`, the `startContent` and the `endContent`.
- **clearButton**: The clear button, it is at the end of the input.
- **helperWrapper**: Wraps the `description` and the `errorMessage`.
- **description**: The description of the date-input.
- **errorMessage**: The error message of the date-input.

<Spacer y={4} />

## Data Attributes

`DateInput` has the following attributes on the `base` element:

- **data-slot**:
  All slots have this prop. which slot the element represents(e.g. `slot`).
- **data-invalid**:
  When the date-input is invalid. Based on `isInvalid` prop.
- **data-required**:
  When the date-input is required. Based on `isRequired` prop.
- **data-readonly**:
  When the date-input is readonly. Based on `isReadOnly` prop.
- **data-disabled**:
  When the date-input is disabled. Based on `isDisabled` prop.
- **data-has-helper**:
  When the date-input has helper text(`errorMessage` or `description`). Base on those two props.
- **data-has-start-content**:
  When the date-input has a start content. Base on those `startContent` prop.
- **data-has-end-content**:
  When the date-input has a end content. Base on those `endContent` prop.

<Spacer y={4} />

## Accessibility

- Built with a native `<input>` element.
- Visual and ARIA labeling support.
- Change, clipboard, composition, selection, and input event support.
- Required and invalid states exposed to assistive technology via ARIA.
- Support for description and error message help text linked to the input via ARIA.
- Each date and time unit is displayed as an individually focusable and editable segment, which allows users an easy way to edit dates using the keyboard, in any date format and locale.
- Date segments are editable using an easy to use numeric keypad, and all interactions are accessible using touch-based screen readers.

<Spacer y={4} />

## API

### DateInput Props

<APITable
  data={[
    {
      attribute: "label",
      type: "ReactNode",
      description: "The content to display as the label.",
      default: "-"
    },
    {
      attribute: "value",
      type: "DateValue",
      description: "The current value of the date input (controlled).",
      default: "-"
    },
    {
      attribute: "defaultValue",
      type: "DateValue",
      description: "The default value of the date input (uncontrolled).",
      default: "-"
    },
    {
      attribute: "variant",
      type: "flat | bordered | faded | underlined",
      description: "The variant of the date input.",
      default: "flat"
    },
    {
      attribute: "color",
      type: "default | primary | secondary | success | warning | danger",
      description: "The color of the date input.",
      default: "default"
    },
    {
      attribute: "size",
      type: "sm | md | lg",
      description: "The size of the date input.",
      default: "md"
    },
    {
      attribute: "radius",
      type: "none | sm | md | lg | full",
      description: "The radius of the date input.",
      default: "-"
    },
    {
      attribute: "placeholderValue",
      type: "DateValue",
      description: "A placeholder time that influences the format of the placeholder shown when no value is selected. Defaults current date at midnight.",
      default: "-"
    },
    {
      attribute: "minValue",
      type: "DateValue",
      description: "The minimum allowed date that a user may select.",
      default: "-"
    },
    {
      attribute: "maxValue",
      type: "DateValue",
      description: "The maximum allowed date that a user may select.",
      default: "-"
    },
    {
      attribute: "locale",
      type: "string",
      description: "The locale to display and edit the value according to.",
      default: "-"
    },
    {
      attribute: "description",
      type: "ReactNode",
      description: "A description for the date input. Provides a hint such as specific requirements for what to choose.",
      default: "-"
    },
    {
      attribute: "errorMessage",
      type: "ReactNode | (v: ValidationResult) => ReactNode",
      description: "An error message for the date input.",
      default: "-"
    },
    {
      attribute: "labelPlacement",
      type: "inside | outside | outside-left",
      description: "The position of the label.",
      default: "inside"
    },
    {
      attribute: "isRequired",
      type: "boolean",
      description: "Whether user input is required on the input before form submission.",
      default: "false"
    },
    {
      attribute: "isReadOnly",
      type: "boolean",
      description: "Whether the input can be selected but not changed by the user.",
      default: "-"
    },
    {
      attribute: "isDisabled",
      type: "boolean",
      description: "Whether the input is disabled.",
      default: "false"
    },
    {
      attribute: "isInvalid",
      type: "boolean",
      description: "Whether the input value is invalid.",
      default: "false"
    },
    {
      attribute: "autoFocus",
      type: "boolean",
      description: "Whether the element should receive focus on render.",
      default: "false"
    },
    {
      attribute: "hideTimeZone",
      type: "boolean",
      description: "Whether to hide the time zone abbreviation.",
      default: "false"
    },
    {
      attribute: "disableAnimation",
      type: "boolean",
      description: "Whether to disable animations.",
      default: "false"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<\"base\" | \"label\" | \"inputWrapper\" | \"input\" | \"segment\" | \"helperWrapper\" | \"description\" | \"errorMessage\", string>>",
      description: "Allows to set custom class names for the date-input slots.",
      default: "-"
    }
  ]}
/>

### DateInput Events

<APITable
  data={[
    {
      attribute: "onChange",
      type: "(value: ZonedDateTime | CalendarDate | CalendarDateTime) => void",
      description: "Handler that is called when the date-input's value changes.",
      default: "-"
    },
    {
      attribute: "onFocus",
      type: "(e: FocusEvent<HTMLInputElement>) => void",
      description: "Handler that is called when the element receives focus.",
      default: "-"
    },
    {
      attribute: "onBlur",
      type: "(e: FocusEvent<HTMLInputElement>) => void",
      description: "Handler that is called when the element loses focus.",
      default: "-"
    },
    {
      attribute: "onFocusChange",
      type: "(isFocused: boolean) => void",
      description: "Handler that is called when the element's focus status changes.",
      default: "-"
    },
    {
      attribute: "onKeyDown",
      type: "(e: KeyboardEvent) => void",
      description: "Handler that is called when a key is pressed.",
      default: "-"
    },
    {
      attribute: "onKeyUp",
      type: "(e: KeyboardEvent) => void",
      description: "Handler that is called when a key is released.",
      default: "-"
    }
  ]}
/>
